home *** CD-ROM | disk | FTP | other *** search
/ PC World 2006 July & August / PCWorld_2006-07-08_cd.bin / komunikace / apache / apache_2[1].2.2-win32-x86-no_ssl.msi / Data1.cab / _DA389B8F23E49D3965A074BD77417A21 < prev    next >
Extensible Markup Language  |  2006-02-06  |  77KB  |  1,560 lines
  1. <?xml version="1.0" encoding="ISO-8859-1"?>
  2. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  3. <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
  4.         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  5.               This file is generated from xml source: DO NOT EDIT
  6.         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  7.       -->
  8. <title>mod_rewrite - Apache HTTP Server</title>
  9. <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10. <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11. <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
  12. <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  13. <body>
  14. <div id="page-header">
  15. <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  16. <p class="apache">Apache HTTP Server Version 2.2</p>
  17. <img alt="" src="../images/feather.gif" /></div>
  18. <div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
  19. <div id="path">
  20. <a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.2</a> > <a href="./">Modules</a></div>
  21. <div id="page-content">
  22. <div id="preamble"><h1>Apache Module mod_rewrite</h1>
  23. <div class="toplang">
  24. <p><span>Available Languages: </span><a href="../en/mod/mod_rewrite.html" title="English"> en </a></p>
  25. </div>
  26. <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Provides a rule-based rewriting engine to rewrite requested
  27. URLs on the fly</td></tr>
  28. <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  29. <tr><th><a href="module-dict.html#ModuleIdentifier">ModuleáIdentifier:</a></th><td>rewrite_module</td></tr>
  30. <tr><th><a href="module-dict.html#SourceFile">SourceáFile:</a></th><td>mod_rewrite.c</td></tr>
  31. <tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 1.3 and later</td></tr></table>
  32. <h3>Summary</h3>
  33.  
  34.       <p>This module uses a rule-based rewriting engine (based on a
  35.       regular-expression parser) to rewrite requested URLs on the
  36.       fly. It supports an unlimited number of rules and an
  37.       unlimited number of attached rule conditions for each rule, to
  38.       provide a really flexible and powerful URL manipulation
  39.       mechanism. The URL manipulations can depend on various tests,
  40.       of server variables, environment variables, HTTP
  41.       headers, or time stamps. Even external database lookups in
  42.       various formats can be used to achieve highly granular URL
  43.       matching.</p>
  44.  
  45.       <p>This module operates on the full URLs (including the
  46.       path-info part) both in per-server context
  47.       (<code>httpd.conf</code>) and per-directory context
  48.       (<code>.htaccess</code>) and can generate query-string
  49.       parts on result. The rewritten result can lead to internal
  50.       sub-processing, external request redirection or even to an
  51.       internal proxy throughput.</p>
  52.  
  53.       <p>Further details, discussion, and examples, are provided in the
  54.       <a href="../rewrite/">detailed mod_rewrite documentation</a>.</p>
  55. </div>
  56. <div id="quickview"><h3 class="directives">Directives</h3>
  57. <ul id="toc">
  58. <li><img alt="" src="../images/down.gif" /> <a href="#rewritebase">RewriteBase</a></li>
  59. <li><img alt="" src="../images/down.gif" /> <a href="#rewritecond">RewriteCond</a></li>
  60. <li><img alt="" src="../images/down.gif" /> <a href="#rewriteengine">RewriteEngine</a></li>
  61. <li><img alt="" src="../images/down.gif" /> <a href="#rewritelock">RewriteLock</a></li>
  62. <li><img alt="" src="../images/down.gif" /> <a href="#rewritelog">RewriteLog</a></li>
  63. <li><img alt="" src="../images/down.gif" /> <a href="#rewriteloglevel">RewriteLogLevel</a></li>
  64. <li><img alt="" src="../images/down.gif" /> <a href="#rewritemap">RewriteMap</a></li>
  65. <li><img alt="" src="../images/down.gif" /> <a href="#rewriteoptions">RewriteOptions</a></li>
  66. <li><img alt="" src="../images/down.gif" /> <a href="#rewriterule">RewriteRule</a></li>
  67. </ul>
  68. <h3>Topics</h3>
  69. <ul id="topics">
  70. <li><img alt="" src="../images/down.gif" /> <a href="#quoting">Quoting Special Characters</a></li>
  71. <li><img alt="" src="../images/down.gif" /> <a href="#EnvVar">Environment Variables</a></li>
  72. <li><img alt="" src="../images/down.gif" /> <a href="#Solutions">Practical Solutions</a></li>
  73. </ul></div>
  74. <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  75. <div class="section">
  76. <h2><a name="quoting" id="quoting">Quoting Special Characters</a></h2>
  77.  
  78.       <p>As of Apache 1.3.20, special characters in
  79.       <em>TestString</em> and <em>Substitution</em> strings can be
  80.       escaped (that is, treated as normal characters without their
  81.       usual special meaning) by prefixing them with a slash ('\')
  82.       character. In other words, you can include an actual
  83.       dollar-sign character in a <em>Substitution</em> string by
  84.       using '<code>\$</code>'; this keeps mod_rewrite from trying
  85.       to treat it as a backreference.</p>
  86. </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  87. <div class="section">
  88. <h2><a name="EnvVar" id="EnvVar">Environment Variables</a></h2>
  89.  
  90.       <p>This module keeps track of two additional (non-standard)
  91.       CGI/SSI environment variables named <code>SCRIPT_URL</code>
  92.       and <code>SCRIPT_URI</code>. These contain the
  93.       <em>logical</em> Web-view to the current resource, while the
  94.       standard CGI/SSI variables <code>SCRIPT_NAME</code> and
  95.       <code>SCRIPT_FILENAME</code> contain the <em>physical</em>
  96.       System-view. </p>
  97.  
  98.       <p>Notice: These variables hold the URI/URL <em>as they were
  99.       initially requested</em>, that is, <em>before</em> any
  100.       rewriting. This is important to note because the rewriting process is
  101.       primarily used to rewrite logical URLs to physical
  102.       pathnames.</p>
  103.  
  104. <div class="example"><h3>Example</h3><pre>
  105. SCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html
  106. SCRIPT_FILENAME=/u/rse/.www/index.html
  107. SCRIPT_URL=/u/rse/
  108. SCRIPT_URI=http://en1.engelschall.com/u/rse/
  109. </pre></div>
  110.  
  111. </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  112. <div class="section">
  113. <h2><a name="Solutions" id="Solutions">Practical Solutions</a></h2>
  114.  
  115.     <p>For numerous examples of common, and not-so-common, uses for
  116.     mod_rewrite, see the <a href="../rewrite/rewrite_guide.html">Rewrite
  117.     Guide</a>, and the <a href="../rewrite/rewrite_guide_advanced.html">Advanced Rewrite
  118.     Guide</a> documents.</p>
  119.  
  120. </div>
  121. <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  122. <div class="directive-section"><h2><a name="RewriteBase" id="RewriteBase">RewriteBase</a> <a name="rewritebase" id="rewritebase">Directive</a></h2>
  123. <table class="directive">
  124. <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the base URL for per-directory rewrites</td></tr>
  125. <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteBase <em>URL-path</em></code></td></tr>
  126. <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>See usage for information.</code></td></tr>
  127. <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
  128. <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
  129. <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  130. <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
  131. </table>
  132.       <p>The <code class="directive">RewriteBase</code> directive explicitly
  133.       sets the base URL for per-directory rewrites. As you will see
  134.       below, <code class="directive"><a href="#rewriterule">RewriteRule</a></code>
  135.       can be used in per-directory config files
  136.       (<code>.htaccess</code>). In such a case, it will act locally,
  137.       stripping the local directory prefix before processing, and applying
  138.       rewrite rules only to the remainder. When processing is complete, the 
  139.       prefix is automatically added back to the
  140.       path. The default setting is; <code class="directive">RewriteBase</code> <em>physical-directory-path</em></p>
  141.  
  142.       <p>When a substitution occurs for a new URL, this module has
  143.       to re-inject the URL into the server processing. To be able
  144.       to do this it needs to know what the corresponding URL-prefix
  145.       or URL-base is. By default this prefix is the corresponding
  146.       filepath itself. <strong>However, for most websites, URLs are NOT
  147.       directly related to physical filename paths, so this
  148.       assumption will often be wrong!</strong> Therefore, you can 
  149.       use the <code>RewriteBase</code> directive to specify the
  150.       correct URL-prefix.</p>
  151.  
  152. <div class="note"> If your webserver's URLs are <strong>not</strong> directly
  153. related to physical file paths, you will need to use
  154. <code class="directive">RewriteBase</code> in every <code>.htaccess</code>
  155. file where you want to use <code class="directive"><a href="#rewriterule">RewriteRule</a></code> directives.
  156. </div>
  157.  
  158.         <p> For example, assume the following per-directory config file:</p>
  159.  
  160. <div class="example"><pre>
  161. #
  162. #  /abc/def/.htaccess -- per-dir config file for directory /abc/def
  163. #  Remember: /abc/def is the physical path of /xyz, <em>i.e.</em>, the server
  164. #            has a 'Alias /xyz /abc/def' directive <em>e.g.</em>
  165. #
  166.  
  167. RewriteEngine On
  168.  
  169. #  let the server know that we were reached via /xyz and not
  170. #  via the physical path prefix /abc/def
  171. RewriteBase   /xyz
  172.  
  173. #  now the rewriting rules
  174. RewriteRule   ^oldstuff\.html$  newstuff.html
  175. </pre></div>
  176.  
  177.         <p>In the above example, a request to
  178.         <code>/xyz/oldstuff.html</code> gets correctly rewritten to
  179.         the physical file <code>/abc/def/newstuff.html</code>.</p>
  180.  
  181. <div class="note"><h3>For Apache Hackers</h3>
  182. <p>The following list gives detailed information about
  183.               the internal processing steps:</p>
  184. <pre>
  185. Request:
  186.   /xyz/oldstuff.html
  187.  
  188. Internal Processing:
  189.   /xyz/oldstuff.html     -> /abc/def/oldstuff.html  (per-server Alias)
  190.   /abc/def/oldstuff.html -> /abc/def/newstuff.html  (per-dir    RewriteRule)
  191.   /abc/def/newstuff.html -> /xyz/newstuff.html      (per-dir    RewriteBase)
  192.   /xyz/newstuff.html     -> /abc/def/newstuff.html  (per-server Alias)
  193.  
  194. Result:
  195.   /abc/def/newstuff.html
  196. </pre>
  197.               <p>This seems very complicated, but is in fact
  198.               correct Apache internal processing. Because the
  199.               per-directory rewriting comes late in the
  200.               process, the rewritten request
  201.               has to be re-injected into the Apache kernel. 
  202.               This is not the serious overhead it may seem to be - 
  203.               this re-injection is completely internal to the 
  204.           Apache server (and the same procedure is used by 
  205.           many other operations within Apache).</p> 
  206. </div>
  207.  
  208.  
  209. </div>
  210. <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  211. <div class="directive-section"><h2><a name="RewriteCond" id="RewriteCond">RewriteCond</a> <a name="rewritecond" id="rewritecond">Directive</a></h2>
  212. <table class="directive">
  213. <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines a condition under which rewriting will take place
  214. </td></tr>
  215. <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code> RewriteCond
  216.       <em>TestString</em> <em>CondPattern</em></code></td></tr>
  217. <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
  218. <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
  219. <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  220. <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
  221. </table>
  222.       <p>The <code class="directive">RewriteCond</code> directive defines a
  223.       rule condition. One or more <code class="directive">RewriteCond</code>
  224.       can precede a <code class="directive"><a href="#rewriterule">RewriteRule</a></code> 
  225.       directive. The following rule is then only used if both
  226.       the current state of the URI matches its pattern, <strong>and</strong> if these conditions are met.</p>
  227.  
  228.       <p><em>TestString</em> is a string which can contain the
  229.       following expanded constructs in addition to plain text:</p>
  230.  
  231.       <ul>
  232.         <li>
  233.           <strong>RewriteRule backreferences</strong>: These are
  234.           backreferences of the form <strong><code>$N</code></strong>
  235.           (0 <= N <= 9), which provide access to the grouped
  236.           parts (in parentheses) of the pattern, from the
  237.           <code>RewriteRule</code> which is subject to the current 
  238.       set of <code>RewriteCond</code> conditions..
  239.         </li>
  240.         <li>
  241.           <strong>RewriteCond backreferences</strong>: These are
  242.           backreferences of the form <strong><code>%N</code></strong>
  243.           (1 <= N <= 9), which provide access to the grouped
  244.           parts (again, in parentheses) of the pattern, from the last matched
  245.           <code>RewriteCond</code> in the current set
  246.           of conditions.
  247.         </li>
  248.         <li>
  249.           <strong>RewriteMap expansions</strong>: These are
  250.           expansions of the form <strong><code>${mapname:key|default}</code></strong>.
  251.           See <a href="#mapfunc">the documentation for
  252.           RewriteMap</a> for more details.
  253.         </li>
  254.         <li>
  255.           <strong>Server-Variables</strong>: These are variables of
  256.           the form 
  257.             <strong><code>%{</code> <em>NAME_OF_VARIABLE</em>
  258.             <code>}</code></strong>
  259.           where <em>NAME_OF_VARIABLE</em> can be a string taken
  260.           from the following list: 
  261.  
  262.           <table>
  263.           
  264.             <tr>
  265.               <th>HTTP headers:</th> <th>connection & request:</th> <th />
  266.         </tr>
  267.  
  268.             <tr>
  269.           <td>
  270.          HTTP_USER_AGENT<br />
  271.                  HTTP_REFERER<br />
  272.                  HTTP_COOKIE<br />
  273.                  HTTP_FORWARDED<br />
  274.                  HTTP_HOST<br />
  275.                  HTTP_PROXY_CONNECTION<br />
  276.                  HTTP_ACCEPT<br />
  277.               </td>
  278.  
  279.               <td>
  280.                  REMOTE_ADDR<br />
  281.                  REMOTE_HOST<br />
  282.                  REMOTE_PORT<br />
  283.                  REMOTE_USER<br />
  284.                  REMOTE_IDENT<br />
  285.                  REQUEST_METHOD<br />
  286.                  SCRIPT_FILENAME<br />
  287.                  PATH_INFO<br />
  288.                  QUERY_STRING<br />
  289.                  AUTH_TYPE<br />
  290.               </td>
  291.           
  292.           <td />
  293.             </tr>
  294.  
  295.             <tr>
  296.               <th>server internals:</th> <th>date and time:</th> <th>specials:</th>
  297.         </tr>
  298.  
  299.             <tr>
  300.           <td>
  301.              DOCUMENT_ROOT<br />
  302.                  SERVER_ADMIN<br />
  303.                  SERVER_NAME<br />
  304.                  SERVER_ADDR<br />
  305.                  SERVER_PORT<br />
  306.                  SERVER_PROTOCOL<br />
  307.                  SERVER_SOFTWARE<br />
  308.               </td>
  309.  
  310.               <td>
  311.                  TIME_YEAR<br />
  312.                  TIME_MON<br />
  313.                  TIME_DAY<br />
  314.                  TIME_HOUR<br />
  315.                  TIME_MIN<br />
  316.                  TIME_SEC<br />
  317.                  TIME_WDAY<br />
  318.                  TIME<br />
  319.               </td>
  320.  
  321.               <td>
  322.                  API_VERSION<br />
  323.                  THE_REQUEST<br />
  324.                  REQUEST_URI<br />
  325.                  REQUEST_FILENAME<br />
  326.                  IS_SUBREQ<br />
  327.                  HTTPS<br />
  328.               </td>
  329.             </tr>
  330.           </table>
  331.  
  332.                 <p>These variables all
  333.                 correspond to the similarly named HTTP
  334.                 MIME-headers, C variables of the Apache server or
  335.                 <code>struct tm</code> fields of the Unix system.
  336.                 Most are documented elsewhere in the Manual or in
  337.                 the CGI specification. Those that are special to
  338.                 mod_rewrite include those below.</p>
  339.     <div class="note">
  340.                 <dl>
  341.                   <dt><code>IS_SUBREQ</code></dt>
  342.  
  343.                   <dd>Will contain the text "true" if the request
  344.                   currently being processed is a sub-request,
  345.                   "false" otherwise. Sub-requests may be generated
  346.                   by modules that need to resolve additional files
  347.                   or URIs in order to complete their tasks.</dd>
  348.  
  349.                   <dt><code>API_VERSION</code></dt>
  350.  
  351.                   <dd>This is the version of the Apache module API
  352.                   (the internal interface between server and
  353.                   module) in the current httpd build, as defined in
  354.                   include/ap_mmn.h. The module API version
  355.                   corresponds to the version of Apache in use (in
  356.                   the release version of Apache 1.3.14, for
  357.                   instance, it is 19990320:10), but is mainly of
  358.                   interest to module authors.</dd>
  359.  
  360.                   <dt><code>THE_REQUEST</code></dt>
  361.  
  362.                   <dd>The full HTTP request line sent by the
  363.                   browser to the server (e.g., "<code>GET
  364.                   /index.html HTTP/1.1</code>"). This does not
  365.                   include any additional headers sent by the
  366.                   browser.</dd>
  367.  
  368.                   <dt><code>REQUEST_URI</code></dt>
  369.  
  370.                   <dd>The resource requested in the HTTP request
  371.                   line. (In the example above, this would be
  372.                   "/index.html".)</dd>
  373.  
  374.                   <dt><code>REQUEST_FILENAME</code></dt>
  375.  
  376.                   <dd>The full local filesystem path to the file or
  377.                   script matching the request.</dd>
  378.  
  379.                   <dt><code>HTTPS</code></dt>
  380.  
  381.                   <dd>Will contain the text "on" if the connection is
  382.                   using SSL/TLS, or "off" otherwise.  (This variable
  383.                   can be safely used regardless of whether or not
  384.                   <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is loaded).</dd>
  385.  
  386.                 </dl>
  387. </div>
  388.         </li>
  389.       </ul>
  390.  
  391.       <p>Other things you should be aware of:</p>
  392.  
  393.       <ol>
  394.         <li>The variables SCRIPT_FILENAME and REQUEST_FILENAME
  395.         contain the same value - the value of the
  396.         <code>filename</code> field of the internal
  397.         <code>request_rec</code> structure of the Apache server.
  398.         The first name is the commonly known CGI variable name
  399.         while the second is the appropriate counterpart of
  400.         REQUEST_URI (which contains the value of the
  401.         <code>uri</code> field of <code>request_rec</code>).</li>
  402.  
  403.         <li>
  404.         <code>%{ENV:variable}</code>, where <em>variable</em> can be
  405.     any environment variable, is also available. 
  406.     This is looked-up via internal
  407.         Apache structures and (if not found there) via
  408.         <code>getenv()</code> from the Apache server process.</li>
  409.  
  410.         <li>
  411.         <code>%{SSL:variable}</code>, where <em>variable</em> is the
  412.         name of an <a href="mod_ssl.html#envvars">SSL environment
  413.         variable</a>, can be used whether or not
  414.         <code class="module"><a href="../mod/mod_ssl.html">mod_ssl</a></code> is loaded, but will always expand to
  415.         the empty string if it is not.  Example:
  416.         <code>%{SSL:SSL_CIPHER_USEKEYSIZE}</code> may expand to
  417.         <code>128</code>.</li>
  418.  
  419.         <li>
  420.         <code>%{HTTP:header}</code>, where <em>header</em> can be
  421.     any HTTP MIME-header name, can always be used to obtain the
  422.     value of a header sent in the HTTP request.
  423.         Example: <code>%{HTTP:Proxy-Connection}</code> is
  424.         the value of the HTTP header
  425.         ``<code>Proxy-Connection:</code>''.</li>
  426.  
  427.         <li>
  428.         <code>%{LA-U:variable}</code> can be used for look-aheads which perform
  429.         an internal (URL-based) sub-request to determine the final
  430.     value of <em>variable</em>. This can be used to access
  431.         variable for rewriting which is not available at the current 
  432.     stage, but will be set in a later phase.
  433.     <p>For instance, to rewrite according to the
  434.         <code>REMOTE_USER</code> variable from within the
  435.         per-server context (<code>httpd.conf</code> file) you must
  436.         use <code>%{LA-U:REMOTE_USER}</code> - this
  437.         variable is set by the authorization phases, which come
  438.     <em>after</em> the URL translation phase (during which mod_rewrite
  439.     operates).</p>
  440.     <p>On the other hand, because mod_rewrite implements
  441.         its per-directory context (<code>.htaccess</code> file) via
  442.         the Fixup phase of the API and because the authorization
  443.         phases come <em>before</em> this phase, you just can use
  444.     <code>%{REMOTE_USER}</code> in that context.</p></li>
  445.  
  446.         <li>
  447.         <code>%{LA-F:variable}</code> can be used to perform an internal
  448.         (filename-based) sub-request, to determine the final value
  449.         of <em>variable</em>. Most of the time, this is the same as
  450.         LA-U above.</li>
  451.       </ol>
  452.  
  453.       <p><em>CondPattern</em> is the condition pattern,
  454.        a regular expression which is applied to the
  455.       current instance of the <em>TestString</em>.
  456.       <em>TestString</em> is first evaluated, before being matched against
  457.       <em>CondPattern</em>.</p>
  458.  
  459.       <p><strong>Remember:</strong> <em>CondPattern</em> is a
  460.       <em>perl compatible regular expression</em> with some
  461.       additions:</p>
  462.  
  463.       <ol>
  464.         <li>You can prefix the pattern string with a
  465.         '<code>!</code>' character (exclamation mark) to specify a
  466.         <strong>non</strong>-matching pattern.</li>
  467.  
  468.         <li>
  469.           There are some special variants of <em>CondPatterns</em>.
  470.           Instead of real regular expression strings you can also
  471.           use one of the following: 
  472.  
  473.           <ul>
  474.             <li>'<strong><CondPattern</strong>' (lexicographically 
  475.         precedes)<br />
  476.             Treats the <em>CondPattern</em> as a plain string and
  477.             compares it lexicographically to <em>TestString</em>. True if
  478.             <em>TestString</em> lexicographically precedes
  479.             <em>CondPattern</em>.</li>
  480.  
  481.             <li>'<strong>>CondPattern</strong>' (lexicographically
  482.             follows)<br />
  483.             Treats the <em>CondPattern</em> as a plain string and
  484.             compares it lexicographically to <em>TestString</em>. True if
  485.             <em>TestString</em> lexicographically follows
  486.             <em>CondPattern</em>.</li>
  487.  
  488.             <li>'<strong>=CondPattern</strong>' (lexicographically
  489.             equal)<br />
  490.             Treats the <em>CondPattern</em> as a plain string and
  491.             compares it lexicographically to <em>TestString</em>. True if
  492.             <em>TestString</em> is lexicographically equal to
  493.             <em>CondPattern</em> (the two strings are exactly
  494.             equal, character for character). If <em>CondPattern</em>
  495.             is <code>""</code> (two quotation marks) this
  496.             compares <em>TestString</em> to the empty string.</li>
  497.  
  498.             <li>'<strong>-d</strong>' (is
  499.             <strong>d</strong>irectory)<br />
  500.              Treats the <em>TestString</em> as a pathname and tests
  501.             whether or not it exists, and is a directory.</li>
  502.  
  503.             <li>'<strong>-f</strong>' (is regular
  504.             <strong>f</strong>ile)<br />
  505.              Treats the <em>TestString</em> as a pathname and tests
  506.             whether or not it exists, and is a regular file.</li>
  507.  
  508.             <li>'<strong>-s</strong>' (is regular file, with
  509.             <strong>s</strong>ize)<br />
  510.             Treats the <em>TestString</em> as a pathname and tests
  511.             whether or not it exists, and is a regular file with size greater
  512.             than zero.</li>
  513.  
  514.             <li>'<strong>-l</strong>' (is symbolic
  515.             <strong>l</strong>ink)<br />
  516.             Treats the <em>TestString</em> as a pathname and tests
  517.             whether or not it exists, and is a symbolic link.</li>
  518.  
  519.             <li>'<strong>-x</strong>' (has e<strong>x</strong>ecutable
  520.             permissions)<br />
  521.             Treats the <em>TestString</em> as a pathname and tests
  522.         whether or not it exists, and has executable permissions. 
  523.         These permissions are determined according to 
  524.         the underlying OS.</li>
  525.  
  526.             <li>'<strong>-F</strong>' (is existing file, via
  527.             subrequest)<br />
  528.             Checks whether or not <em>TestString</em> is a valid file,
  529.             accessible via all the server's currently-configured
  530.             access controls for that path. This uses an internal
  531.             subrequest to do the check, so use it with care -
  532.             it can impact your server's performance!</li>
  533.  
  534.             <li>'<strong>-U</strong>' (is existing URL, via
  535.             subrequest)<br />
  536.             Checks whether or not <em>TestString</em> is a valid URL,
  537.             accessible via all the server's currently-configured
  538.             access controls for that path. This uses an internal
  539.             subrequest to do the check, so use it with care - 
  540.             it can impact your server's performance!</li>
  541.           </ul>
  542.  
  543. <div class="note"><h3>Note:</h3>
  544.               All of these tests can
  545.               also be prefixed by an exclamation mark ('!') to
  546.               negate their meaning.
  547. </div>
  548.         </li>
  549.  
  550.     <li>You can also set special flags for
  551.       <em>CondPattern</em> by appending
  552.         <strong><code>[</code><em>flags</em><code>]</code></strong>
  553.       as the third argument to the <code>RewriteCond</code>
  554.       directive, where <em>flags</em> is a comma-separated list of any of the
  555.       following flags:
  556.  
  557.       <ul>
  558.         <li>'<strong><code>nocase|NC</code></strong>'
  559.         (<strong>n</strong>o <strong>c</strong>ase)<br />
  560.         This makes the test case-insensitive - differences 
  561.     between 'A-Z' and 'a-z' are ignored, both in the
  562.         expanded <em>TestString</em> and the <em>CondPattern</em>.
  563.         This flag is effective only for comparisons between
  564.         <em>TestString</em> and <em>CondPattern</em>. It has no
  565.         effect on filesystem and subrequest checks.</li>
  566.  
  567.         <li>
  568.           '<strong><code>ornext|OR</code></strong>'
  569.           (<strong>or</strong> next condition)<br />
  570.           Use this to combine rule conditions with a local OR
  571.           instead of the implicit AND. Typical example: 
  572.  
  573. <div class="example"><pre>
  574. RewriteCond %{REMOTE_HOST}  ^host1.*  [OR]
  575. RewriteCond %{REMOTE_HOST}  ^host2.*  [OR]
  576. RewriteCond %{REMOTE_HOST}  ^host3.*
  577. RewriteRule ...some special stuff for any of these hosts...
  578. </pre></div>
  579.  
  580.           Without this flag you would have to write the condition/rule
  581.           pair three times.
  582.         </li>
  583.       </ul>
  584.       </li>
  585.      </ol>
  586.  
  587.       <p><strong>Example:</strong></p>
  588.  
  589.        <p>To rewrite the Homepage of a site according to the
  590.         ``<code>User-Agent:</code>'' header of the request, you can
  591.         use the following: </p>
  592.  
  593. <div class="example"><pre>
  594. RewriteCond  %{HTTP_USER_AGENT}  ^Mozilla.*
  595. RewriteRule  ^/$                 /homepage.max.html  [L]
  596.  
  597. RewriteCond  %{HTTP_USER_AGENT}  ^Lynx.*
  598. RewriteRule  ^/$                 /homepage.min.html  [L]
  599.  
  600. RewriteRule  ^/$                 /homepage.std.html  [L]
  601. </pre></div>
  602.  
  603.         <p>Explanation: If you use a browser which identifies itself 
  604.     as 'Mozilla' (including Netscape Navigator, Mozilla etc), then you
  605.         get the max homepage (which could include frames, or other special
  606.     features).
  607.         If you use the Lynx browser (which is terminal-based), then
  608.     you get the min homepage (which could be a version designed for 
  609.     easy, text-only browsing).
  610.     If neither of these conditions apply (you use any other browser,
  611.     or your browser identifies itself as something non-standard), you get
  612.         the std (standard) homepage.</p>
  613.  
  614.  
  615. </div>
  616. <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  617. <div class="directive-section"><h2><a name="RewriteEngine" id="RewriteEngine">RewriteEngine</a> <a name="rewriteengine" id="rewriteengine">Directive</a></h2>
  618. <table class="directive">
  619. <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables or disables runtime rewriting engine</td></tr>
  620. <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteEngine on|off</code></td></tr>
  621. <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>RewriteEngine off</code></td></tr>
  622. <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
  623. <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
  624. <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  625. <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
  626. </table>       
  627.  
  628.       <p>The <code class="directive">RewriteEngine</code> directive enables or
  629.       disables the runtime rewriting engine. If it is set to
  630.       <code>off</code> this module does no runtime processing at
  631.       all. It does not even update the <code>SCRIPT_URx</code>
  632.       environment variables.</p>
  633.  
  634.       <p>Use this directive to disable the module instead of
  635.       commenting out all the <code class="directive"><a href="#rewriterule">RewriteRule</a></code> directives!</p>
  636.  
  637.       <p>Note that, by default, rewrite configurations are not
  638.       inherited. This means that you need to have a
  639.       <code>RewriteEngine on</code> directive for each virtual host
  640.       in which you wish to use it.</p>
  641.  
  642. </div>
  643. <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  644. <div class="directive-section"><h2><a name="RewriteLock" id="RewriteLock">RewriteLock</a> <a name="rewritelock" id="rewritelock">Directive</a></h2>
  645. <table class="directive">
  646. <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the name of the lock file used for <code class="directive"><a href="#rewritemap">RewriteMap</a></code>
  647. synchronization</td></tr>
  648. <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteLock <em>file-path</em></code></td></tr>
  649. <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
  650. <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  651. <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
  652. </table>
  653.       <p>This directive sets the filename for a synchronization
  654.       lockfile which mod_rewrite needs to communicate with <code class="directive"><a href="#rewritemap">RewriteMap</a></code>
  655.       <em>programs</em>. Set this lockfile to a local path (not on a
  656.       NFS-mounted device) when you want to use a rewriting
  657.       map-program. It is not required for other types of rewriting
  658.       maps.</p>
  659.  
  660. </div>
  661. <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  662. <div class="directive-section"><h2><a name="RewriteLog" id="RewriteLog">RewriteLog</a> <a name="rewritelog" id="rewritelog">Directive</a></h2>
  663. <table class="directive">
  664. <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the name of the file used for logging rewrite engine
  665. processing</td></tr>
  666. <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteLog <em>file-path</em></code></td></tr>
  667. <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
  668. <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  669. <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
  670. </table>
  671.       <p>The <code class="directive">RewriteLog</code> directive sets the name
  672.       of the file to which the server logs any rewriting actions it
  673.       performs. If the name does not begin with a slash
  674.       ('<code>/</code>') then it is assumed to be relative to the
  675.       <em>Server Root</em>. The directive should occur only once per
  676.       server config.</p>
  677.  
  678. <div class="note">    To disable the logging of
  679.           rewriting actions it is not recommended to set
  680.           <em>Filename</em> to <code>/dev/null</code>, because
  681.           although the rewriting engine does not then output to a
  682.           logfile it still creates the logfile output internally.
  683.           <strong>This will slow down the server with no advantage
  684.           to the administrator!</strong> To disable logging either
  685.           remove or comment out the <code class="directive">RewriteLog</code>
  686.           directive or use <code>RewriteLogLevel 0</code>!
  687. </div>
  688.  
  689. <div class="note"><h3>Security</h3>
  690.  
  691. See the <a href="../misc/security_tips.html">Apache Security Tips</a>
  692. document for details on how your security could be compromised if the
  693. directory where logfiles are stored is writable by anyone other than
  694. the user that starts the server.
  695. </div>
  696.  
  697. <div class="example"><h3>Example</h3><p><code>
  698. RewriteLog "/usr/local/var/apache/logs/rewrite.log"
  699. </code></p></div>
  700.  
  701.  
  702. </div>
  703. <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  704. <div class="directive-section"><h2><a name="RewriteLogLevel" id="RewriteLogLevel">RewriteLogLevel</a> <a name="rewriteloglevel" id="rewriteloglevel">Directive</a></h2>
  705. <table class="directive">
  706. <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the verbosity of the log file used by the rewrite
  707. engine</td></tr>
  708. <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteLogLevel <em>Level</em></code></td></tr>
  709. <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>RewriteLogLevel 0</code></td></tr>
  710. <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
  711. <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  712. <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
  713. </table>
  714.       <p>The <code class="directive">RewriteLogLevel</code> directive sets the
  715.       verbosity level of the rewriting logfile. The default level 0
  716.       means no logging, while 9 or more means that practically all
  717.       actions are logged.</p>
  718.  
  719.       <p>To disable the logging of rewriting actions simply set
  720.       <em>Level</em> to 0. This disables all rewrite action
  721.       logs.</p>
  722.  
  723. <div class="note"> Using a high value for
  724.           <em>Level</em> will slow down your Apache server
  725.           dramatically! Use the rewriting logfile at a
  726.           <em>Level</em> greater than 2 only for debugging!
  727. </div>
  728.  
  729. <div class="example"><h3>Example</h3><p><code>
  730. RewriteLogLevel 3
  731. </code></p></div>
  732.  
  733.  
  734. </div>
  735. <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  736. <div class="directive-section"><h2><a name="RewriteMap" id="RewriteMap">RewriteMap</a> <a name="rewritemap" id="rewritemap">Directive</a></h2>
  737. <table class="directive">
  738. <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines a mapping function for key-lookup</td></tr>
  739. <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
  740. </code></td></tr>
  741. <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
  742. <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  743. <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
  744. <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The choice of different dbm types is available in
  745. Apache 2.0.41 and later</td></tr>
  746. </table>
  747.       <p>The <code class="directive">RewriteMap</code> directive defines a
  748.       <em>Rewriting Map</em> which can be used inside rule
  749.       substitution strings by the mapping-functions to
  750.       insert/substitute fields through a key lookup. The source of
  751.       this lookup can be of various types.</p>
  752.  
  753.       <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is
  754.       the name of the map and will be used to specify a
  755.       mapping-function for the substitution strings of a rewriting
  756.       rule via one of the following constructs:</p>
  757.  
  758.       <p class="indent">
  759.         <strong><code>${</code> <em>MapName</em> <code>:</code>
  760.         <em>LookupKey</em> <code>}</code><br />
  761.          <code>${</code> <em>MapName</em> <code>:</code>
  762.         <em>LookupKey</em> <code>|</code> <em>DefaultValue</em>
  763.         <code>}</code></strong>
  764.       </p>
  765.  
  766.       <p>When such a construct occurs, the map <em>MapName</em> is
  767.       consulted and the key <em>LookupKey</em> is looked-up. If the
  768.       key is found, the map-function construct is substituted by
  769.       <em>SubstValue</em>. If the key is not found then it is
  770.       substituted by <em>DefaultValue</em> or by the empty string
  771.       if no <em>DefaultValue</em> was specified.</p>
  772.  
  773.       <p>For example, you might define a
  774.       <code class="directive">RewriteMap</code> as:</p>
  775.  
  776.       <div class="example"><p><code>
  777.       RewriteMap examplemap txt:/path/to/file/map.txt
  778.       </code></p></div>
  779.  
  780.       <p>You would then be able to use this map in a
  781.       <code class="directive">RewriteRule</code> as follows:</p>
  782.  
  783.       <div class="example"><p><code>
  784.       RewriteRule ^/ex/(.*) ${examplemap:$1}
  785.       </code></p></div>
  786.  
  787.       <p>The following combinations for <em>MapType</em> and
  788.       <em>MapSource</em> can be used:</p>
  789.  
  790.       <ul>
  791.         <li>
  792.           <strong>Standard Plain Text</strong><br />
  793.            MapType: <code>txt</code>, MapSource: Unix filesystem
  794.           path to valid regular file 
  795.  
  796.           <p>This is the standard rewriting map feature where the
  797.           <em>MapSource</em> is a plain ASCII file containing
  798.           either blank lines, comment lines (starting with a '#'
  799.           character) or pairs like the following - one per
  800.           line.</p>
  801.  
  802.           <p class="indent">
  803.             <strong><em>MatchingKey</em>
  804.             <em>SubstValue</em></strong>
  805.           </p>
  806.  
  807. <div class="example"><h3>Example</h3><pre>
  808. ##
  809. ##  map.txt -- rewriting map
  810. ##
  811.  
  812. Ralf.S.Engelschall    rse   # Bastard Operator From Hell
  813. Mr.Joe.Average        joe   # Mr. Average
  814. </pre></div>
  815.  
  816. <div class="example"><p><code>
  817. RewriteMap real-to-user txt:/path/to/file/map.txt
  818. </code></p></div>
  819.         </li>
  820.  
  821.         <li>
  822.           <strong>Randomized Plain Text</strong><br />
  823.            MapType: <code>rnd</code>, MapSource: Unix filesystem
  824.           path to valid regular file 
  825.  
  826.           <p>This is identical to the Standard Plain Text variant
  827.           above but with a special post-processing feature: After
  828.           looking up a value it is parsed according to contained
  829.           ``<code>|</code>'' characters which have the meaning of
  830.           ``or''. In other words they indicate a set of
  831.           alternatives from which the actual returned value is
  832.           chosen randomly. For example, you might use the following map
  833.           file and directives to provide a random load balancing between
  834.           several back-end server, via a reverse-proxy. Images are sent
  835.           to one of the servers in the 'static' pool, while everything
  836.           else is sent to one of the 'dynamic' pool.</p>
  837.           <p>Example:</p>
  838.  
  839. <div class="example"><h3>Rewrite map file</h3><pre>
  840. ##
  841. ##  map.txt -- rewriting map
  842. ##
  843.  
  844. static   www1|www2|www3|www4
  845. dynamic  www5|www6
  846. </pre></div>
  847.  
  848. <div class="example"><h3>Configuration directives</h3><p><code>
  849. RewriteMap servers rnd:/path/to/file/map.txt<br />
  850. <br />
  851. RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1
  852. [NC,P,L]<br />
  853. RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
  854. </code></p></div>
  855.         </li>
  856.  
  857.         <li>
  858.           <strong>Hash File</strong><br /> MapType:
  859.           <code>dbm[=<em>type</em>]</code>, MapSource: Unix filesystem
  860.           path to valid regular file
  861.  
  862.           <p>Here the source is a binary format DBM file containing
  863.           the same contents as a <em>Plain Text</em> format file, but
  864.           in a special representation which is optimized for really
  865.           fast lookups. The <em>type</em> can be sdbm, gdbm, ndbm, or
  866.           db depending on <a href="../install.html#dbm">compile-time
  867.           settings</a>.  If the <em>type</em> is omitted, the
  868.           compile-time default will be chosen. You can create such a
  869.           file with any DBM tool or with the following Perl
  870.           script.  Be sure to adjust it to create the appropriate
  871.           type of DBM.  The example creates an NDBM file.</p>
  872.  
  873. <div class="example"><pre>
  874. #!/path/to/bin/perl
  875. ##
  876. ##  txt2dbm -- convert txt map to dbm format
  877. ##
  878.  
  879. use NDBM_File;
  880. use Fcntl;
  881.  
  882. ($txtmap, $dbmmap) = @ARGV;
  883.  
  884. open(TXT, "<$txtmap") or die "Couldn't open $txtmap!\n";
  885. tie (%DB, 'NDBM_File', $dbmmap,O_RDWR|O_TRUNC|O_CREAT, 0644)
  886.   or die "Couldn't create $dbmmap!\n";
  887.  
  888. while (<TXT>) {
  889.   next if (/^\s*#/ or /^\s*$/);
  890.   $DB{$1} = $2 if (/^\s*(\S+)\s+(\S+)/);
  891. }
  892.  
  893. untie %DB;
  894. close(TXT);
  895. </pre></div>
  896.  
  897. <div class="example"><p><code>
  898. $ txt2dbm map.txt map.db
  899. </code></p></div>
  900.         </li>
  901.  
  902.         <li>
  903.           <strong>Internal Function</strong><br />
  904.            MapType: <code>int</code>, MapSource: Internal Apache
  905.           function 
  906.  
  907.           <p>Here, the source is an internal Apache function.
  908.           Currently you cannot create your own, but the following
  909.           functions already exist:</p>
  910.  
  911.           <ul>
  912.             <li><strong>toupper</strong>:<br />
  913.              Converts the key to all upper case.</li>
  914.  
  915.             <li><strong>tolower</strong>:<br />
  916.              Converts the key to all lower case.</li>
  917.  
  918.             <li><strong>escape</strong>:<br />
  919.              Translates special characters in the key to
  920.             hex-encodings.</li>
  921.  
  922.             <li><strong>unescape</strong>:<br />
  923.              Translates hex-encodings in the key back to
  924.             special characters.</li>
  925.           </ul>
  926.         </li>
  927.  
  928.         <li>
  929.           <strong>External Rewriting Program</strong><br />
  930.            MapType: <code>prg</code>, MapSource: Unix filesystem
  931.           path to valid regular file 
  932.  
  933.           <p>Here the source is a program, not a map file. To
  934.           create it you can use a language of your choice, but
  935.           the result has to be an executable program (either
  936.           object-code or a script with the magic cookie trick
  937.           '<code>#!/path/to/interpreter</code>' as the first
  938.           line).</p>
  939.  
  940.          <p>This program is started once, when the Apache server
  941.           is started, and then communicates with the rewriting engine
  942.           via its <code>stdin</code> and <code>stdout</code>
  943.           file-handles. For each map-function lookup it will
  944.           receive the key to lookup as a newline-terminated string
  945.           on <code>stdin</code>. It then has to give back the
  946.           looked-up value as a newline-terminated string on
  947.           <code>stdout</code> or the four-character string
  948.           ``<code>NULL</code>'' if it fails (<em>i.e.</em>, there
  949.           is no corresponding value for the given key). A trivial
  950.           program which will implement a 1:1 map (<em>i.e.</em>,
  951.           key == value) could be:</p>
  952.  
  953. <div class="example"><pre>
  954. #!/usr/bin/perl
  955. $| = 1;
  956. while (<STDIN>) {
  957.     # ...put here any transformations or lookups...
  958.     print $_;
  959. }
  960. </pre></div>
  961.  
  962.           <p>But be very careful:</p>
  963.  
  964.           <ol>
  965.             <li>``<em>Keep it simple, stupid</em>'' (KISS).
  966.         If this program hangs, it will cause Apache to hang 
  967.         when trying to use the relevant rewrite rule.</li>
  968.  
  969.             <li>A common mistake is to use buffered I/O on
  970.             <code>stdout</code>. Avoid this, as it will cause a deadloop!
  971.             ``<code>$|=1</code>'' is used above, to prevent this.</li>
  972.  
  973.             <li>The <code class="directive"><a href="#rewritelock">RewriteLock</a></code> directive can 
  974.         be used to define a lockfile which mod_rewrite can use to synchronize 
  975.             communication with the mapping program. By default no such
  976.             synchronization takes place.</li>
  977.           </ol>
  978.         </li>
  979.       </ul>
  980.       <p>The <code class="directive">RewriteMap</code> directive can occur more than
  981.       once. For each mapping-function use one
  982.       <code class="directive">RewriteMap</code> directive to declare its rewriting
  983.       mapfile. While you cannot <strong>declare</strong> a map in
  984.       per-directory context it is of course possible to
  985.       <strong>use</strong> this map in per-directory context. </p>
  986.  
  987. <div class="note"><h3>Note</h3> For plain text and DBM format files the
  988. looked-up keys are cached in-core until the <code>mtime</code> of the
  989. mapfile changes or the server does a restart. This way you can have
  990. map-functions in rules which are used for <strong>every</strong>
  991. request.  This is no problem, because the external lookup only happens
  992. once!
  993. </div>
  994.  
  995.  
  996. </div>
  997. <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  998. <div class="directive-section"><h2><a name="RewriteOptions" id="RewriteOptions">RewriteOptions</a> <a name="rewriteoptions" id="rewriteoptions">Directive</a></h2>
  999. <table class="directive">
  1000. <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets some special options for the rewrite engine</td></tr>
  1001. <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteOptions <var>Options</var></code></td></tr>
  1002. <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
  1003. <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
  1004. <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  1005. <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
  1006. <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td><code>MaxRedirects</code> is no longer available in version 2.1 and
  1007. later</td></tr>
  1008. </table>
  1009.  
  1010.       <p>The <code class="directive">RewriteOptions</code> directive sets some
  1011.       special options for the current per-server or per-directory
  1012.       configuration. The <em>Option</em> string can currently 
  1013.       only be one of the following:</p>
  1014.  
  1015.       <dl>
  1016.       <dt><code>inherit</code></dt>
  1017.       <dd>This forces the current configuration to inherit the
  1018.       configuration of the parent. In per-virtual-server context,
  1019.       this means that the maps, conditions and rules of the main
  1020.       server are inherited. In per-directory context this means
  1021.       that conditions and rules of the parent directory's
  1022.       <code>.htaccess</code> configuration are inherited.</dd>
  1023.       </dl>
  1024.  
  1025. </div>
  1026. <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  1027. <div class="directive-section"><h2><a name="RewriteRule" id="RewriteRule">RewriteRule</a> <a name="rewriterule" id="rewriterule">Directive</a></h2>
  1028. <table class="directive">
  1029. <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines rules for the rewriting engine</td></tr>
  1030. <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteRule
  1031.       <em>Pattern</em> <em>Substitution</em></code></td></tr>
  1032. <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
  1033. <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
  1034. <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  1035. <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
  1036. <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The cookie-flag is available in Apache 2.0.40 and later.</td></tr>
  1037. </table>
  1038.       <p>The <code class="directive">RewriteRule</code> directive is the real
  1039.       rewriting workhorse. The directive can occur more than once, 
  1040.       with each instance defining a single rewrite rule. The
  1041.       order in which these rules are defined is important - this is the order
  1042.       in which they will be applied at run-time.</p>
  1043.  
  1044.       <p><a id="patterns" name="patterns"><em>Pattern</em></a> is
  1045.       a perl compatible <a id="regexp" name="regexp">regular
  1046.       expression</a>, which is applied to the current URL.
  1047.       ``Current'' means the value of the URL when this rule is
  1048.       applied. This may not be the originally requested URL,
  1049.       which may already have matched a previous rule, and have been
  1050.       altered.</p>
  1051.  
  1052.       <p>Some hints on the syntax of <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular 
  1053.       expressions</a>:</p>
  1054.  
  1055. <div class="note"><pre>
  1056. <strong>Text:</strong>
  1057.   <strong><code>.</code></strong>           Any single character
  1058.   <strong><code>[</code></strong>chars<strong><code>]</code></strong>     Character class: Any character of the class ``chars''
  1059.   <strong><code>[^</code></strong>chars<strong><code>]</code></strong>    Character class: Not a character of the class ``chars''
  1060.   text1<strong><code>|</code></strong>text2 Alternative: text1 or text2
  1061.  
  1062. <strong>Quantifiers:</strong>
  1063.   <strong><code>?</code></strong>           0 or 1 occurrences of the preceding text
  1064.   <strong><code>*</code></strong>           0 or N occurrences of the preceding text (N > 0)
  1065.   <strong><code>+</code></strong>           1 or N occurrences of the preceding text (N > 1)
  1066.  
  1067. <strong>Grouping:</strong>
  1068.   <strong><code>(</code></strong>text<strong><code>)</code></strong>      Grouping of text
  1069.               (used either to set the borders of an alternative as above, or
  1070.               to make backreferences, where the <strong>N</strong>th group can 
  1071.               be referred to on the RHS of a RewriteRule as <code>$</code><strong>N</strong>)
  1072.  
  1073. <strong>Anchors:</strong>
  1074.   <strong><code>^</code></strong>           Start-of-line anchor
  1075.   <strong><code>$</code></strong>           End-of-line anchor
  1076.  
  1077. <strong>Escaping:</strong>
  1078.   <strong><code>\</code></strong>char       escape the given char
  1079.               (for instance, to specify the chars "<code>.[]()</code>" <em>etc.</em>)
  1080. </pre></div>
  1081.  
  1082.       <p>For more information about regular expressions, have a look at the
  1083.       perl regular expression manpage ("<a href="http://www.perldoc.com/perl5.6.1/pod/perlre.html">perldoc
  1084.       perlre</a>"). If you are interested in more detailed
  1085.       information about regular expressions and their variants
  1086.       (POSIX regex etc.) the following book is dedicated to this topic:</p>
  1087.  
  1088.       <p class="indent">
  1089.         <em>Mastering Regular Expressions, 2nd Edition</em><br />
  1090.          Jeffrey E.F. Friedl<br />
  1091.          O'Reilly & Associates, Inc. 2002<br />
  1092.          ISBN 0-596-00289-0<br />
  1093.       </p>
  1094.  
  1095.       <p>In mod_rewrite, the NOT character    
  1096.        ('<code>!</code>') is also available as a possible pattern 
  1097.       prefix. This enables you to negate a pattern; to say, for instance:
  1098.       ``<em>if the current URL does <strong>NOT</strong> match this
  1099.       pattern</em>''. This can be used for exceptional cases, where
  1100.       it is easier to match the negative pattern, or as a last
  1101.       default rule.</p>
  1102.  
  1103. <div class="note"><h3>Note</h3>
  1104. When using the NOT character to negate a pattern, you cannot include 
  1105. grouped wildcard parts in that pattern. This is because, when the 
  1106. pattern does NOT match (ie, the negation matches), there are no 
  1107. contents for the groups. Thus, if negated patterns are used, you
  1108. cannot use <code>$N</code> in the substitution string!
  1109. </div>
  1110.  
  1111.       <p>The <a id="rhs" name="rhs"><em>substitution</em></a> of a
  1112.       rewrite rule is the string which is substituted for (or
  1113.       replaces) the original URL which <em>Pattern</em>
  1114.       matched. In addition to plain text, it can include</p>
  1115.  
  1116.       <ol>
  1117.         <li>back-references (<code>$N</code>) to the RewriteRule
  1118.         pattern</li>
  1119.  
  1120.         <li>back-references (<code>%N</code>) to the last matched
  1121.         RewriteCond pattern</li>
  1122.  
  1123.         <li>server-variables as in rule condition test-strings
  1124.         (<code>%{VARNAME}</code>)</li>
  1125.  
  1126.         <li><a href="#mapfunc">mapping-function</a> calls
  1127.         (<code>${mapname:key|default}</code>)</li>
  1128.       </ol>
  1129.       <p>Back-references are identifiers of the form 
  1130.           <code>$</code><strong>N</strong>
  1131.       (<strong>N</strong>=0..9), which will be replaced
  1132.       by the contents of the <strong>N</strong>th group of the
  1133.       matched <em>Pattern</em>. The server-variables are the same
  1134.       as for the <em>TestString</em> of a <code>RewriteCond</code>
  1135.       directive. The mapping-functions come from the
  1136.       <code>RewriteMap</code> directive and are explained there.
  1137.       These three types of variables are expanded in the order above.</p>
  1138.  
  1139.       <p>As already mentioned, all rewrite rules are
  1140.       applied to the <em>Substitution</em> (in the order in which 
  1141.       they are defined
  1142.       in the config file). The URL is <strong>completely
  1143.       replaced</strong> by the <em>Substitution</em> and the
  1144.       rewriting process continues until all rules have been applied,
  1145.       or it is explicitly terminated by a
  1146.       <code><strong>L</strong></code> flag.</p>
  1147.  
  1148.       <p>There is a special substitution string named
  1149.       '<code>-</code>' which means: <strong>NO
  1150.       substitution</strong>! This is useful in providing
  1151.       rewriting rules which <strong>only</strong> match
  1152.       URLs but do not substitute anything for them. It is commonly used 
  1153.       in conjunction with the <strong>C</strong> (chain) flag, in order 
  1154.       to apply more than one pattern before substitution occurs.</p>
  1155.  
  1156.  
  1157.       <p>Additionally you can set special <a name="rewriteflags" id="rewriteflags">flags</a> for <em>Substitution</em> by 
  1158.       appending <strong><code>[</code><em>flags</em><code>]</code></strong>
  1159.       as the third argument to the <code>RewriteRule</code>
  1160.       directive. <em>Flags</em> is a comma-separated list of any of the
  1161.       following flags: </p>
  1162.  
  1163.       <ul>
  1164.         <li>'<strong><code>chain|C</code></strong>'
  1165.         (<strong>c</strong>hained with next rule)<br />
  1166.          This flag chains the current rule with the next rule
  1167.         (which itself can be chained with the following rule,
  1168.         and so on). This has the following effect: if a rule
  1169.         matches, then processing continues as usual - 
  1170.         the flag has no effect. If the rule does
  1171.         <strong>not</strong> match, then all following chained
  1172.         rules are skipped. For instance, it can be used to remove the
  1173.         ``<code>.www</code>'' part, inside a per-directory rule set,
  1174.         when you let an external redirect happen (where the
  1175.         ``<code>.www</code>'' part should not occur!).</li>
  1176.  
  1177.         <li>
  1178.         '<strong><code>cookie|CO=</code></strong><em>NAME</em>:<em>VAL</em>:<em>domain</em>[:<em>lifetime</em>[:<em>path</em>]]'
  1179.         (set <strong>co</strong>okie)<br />
  1180.         This sets a cookie in the client's browser.  The cookie's name
  1181.         is specified by <em>NAME</em> and the value is
  1182.         <em>VAL</em>. The <em>domain</em> field is the domain of the
  1183.         cookie, such as '.apache.org', the optional <em>lifetime</em>
  1184.     is the lifetime of the cookie in minutes, and the optional 
  1185.     <em>path</em> is the path of the cookie</li>
  1186.  
  1187.         <li>
  1188.         '<strong><code>env|E=</code></strong><em>VAR</em>:<em>VAL</em>'
  1189.         (set <strong>e</strong>nvironment variable)<br />
  1190.         This forces an environment variable named <em>VAR</em> to
  1191.         be set to the value <em>VAL</em>, where <em>VAL</em> can
  1192.         contain regexp backreferences (<code>$N</code> and
  1193.         <code>%N</code>) which will be expanded. You can use this
  1194.         flag more than once, to set more than one variable. The
  1195.         variables can later be dereferenced in many situations, most commonly
  1196.     from within XSSI (via <code><!--#echo
  1197.         var="VAR"--></code>) or CGI (<code>$ENV{'VAR'}</code>). 
  1198.     You can also dereference the variable in a later RewriteCond pattern, using
  1199.         <code>%{ENV:VAR}</code>. Use this to strip 
  1200.         information from URLs, while maintaining a record of that information.</li>
  1201.  
  1202.         <li>'<strong><code>forbidden|F</code></strong>' (force URL
  1203.         to be <strong>f</strong>orbidden)<br />
  1204.         This forces the current URL to be forbidden - it immediately 
  1205.     sends back a HTTP response of 403 (FORBIDDEN). 
  1206.     Use this flag in conjunction with
  1207.         appropriate RewriteConds to conditionally block some
  1208.         URLs.</li>
  1209.  
  1210.         <li>'<strong><code>gone|G</code></strong>' (force URL to be
  1211.         <strong>g</strong>one)<br />
  1212.         This forces the current URL to be gone - it
  1213.         immediately sends back a HTTP response of 410 (GONE). Use
  1214.         this flag to mark pages which no longer exist as gone.</li>
  1215.  
  1216.         <li>
  1217.         '<strong><code>handler|H</code></strong>=<em>Content-handler</em>'
  1218.         (force Content <strong>h</strong>andler)<br />
  1219.          Force the Content-handler of the target file to be
  1220.         <em>Content-handler</em>. For instance, this can be used to
  1221.         simulate the <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> directive
  1222.     <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>, 
  1223.     which internally forces all files
  1224.         inside the mapped directory to have a handler of
  1225.         ``<code>cgi-script</code>''.</li>
  1226.  
  1227.         <li>'<strong><code>last|L</code></strong>'
  1228.         (<strong>l</strong>ast rule)<br />
  1229.         Stop the rewriting process here and don't apply any more
  1230.         rewrite rules. This corresponds to the Perl
  1231.         <code>last</code> command or the <code>break</code> command
  1232.         in C. Use this flag to prevent the currently
  1233.         rewritten URL from being rewritten further by following
  1234.         rules. For example, use it to rewrite the root-path URL
  1235.         ('<code>/</code>') to a real one, <em>e.g.</em>,
  1236.         '<code>/e/www/</code>'.</li>
  1237.  
  1238.         <li>'<strong><code>next|N</code></strong>'
  1239.         (<strong>n</strong>ext round)<br />
  1240.         Re-run the rewriting process (starting again with the
  1241.         first rewriting rule). This time, the URL to match is no longer
  1242.         the original URL, but rather the URL returned by the last rewriting rule.
  1243.         This corresponds to the Perl <code>next</code> command or
  1244.         the <code>continue</code> command in C. Use
  1245.         this flag to restart the rewriting process -
  1246.         to immediately go to the top of the loop.<br />
  1247.          <strong>Be careful not to create an infinite
  1248.         loop!</strong></li>
  1249.  
  1250.         <li>'<strong><code>nocase|NC</code></strong>'
  1251.         (<strong>n</strong>o <strong>c</strong>ase)<br />
  1252.         This makes the <em>Pattern</em> case-insensitive,
  1253.         ignoring difference between 'A-Z' and
  1254.         'a-z' when <em>Pattern</em> is matched against the current
  1255.         URL.</li>
  1256.  
  1257.         <li>
  1258.           '<strong><code>noescape|NE</code></strong>'
  1259.           (<strong>n</strong>o URI <strong>e</strong>scaping of
  1260.           output)<br />
  1261.           This flag prevents mod_rewrite from applying the usual URI
  1262.           escaping rules to the result of a rewrite. Ordinarily,
  1263.           special characters (such as '%', '$', ';', and so on)
  1264.           will be escaped into their hexcode equivalents ('%25',
  1265.           '%24', and '%3B', respectively); this flag prevents this
  1266.           from happening. This allows percent symbols to appear in
  1267.           the output, as in 
  1268. <div class="example"><p><code>
  1269.     RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE]
  1270. </code></p></div>
  1271.           which would turn '<code>/foo/zed</code>' into a safe
  1272.           request for '<code>/bar?arg=P1=zed</code>'. 
  1273.         </li>
  1274.  
  1275.         <li>
  1276.           '<strong><code>nosubreq|NS</code></strong>'
  1277.           (<strong>n</strong>ot for internal
  1278.           <strong>s</strong>ub-requests)<br />
  1279.           This flag forces the rewriting engine to skip a
  1280.           rewriting rule if the current request is an internal
  1281.           sub-request. For instance, sub-requests occur internally
  1282.           in Apache when <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> tries to find out
  1283.           information about possible directory default files
  1284.           (<code>index.xxx</code> files). On sub-requests it is not
  1285.           always useful, and can even cause errors, if
  1286.           the complete set of rules are applied. Use this flag to
  1287.           exclude some rules.<br />
  1288.           To decide whether or not to use this rule: if you
  1289.           prefix URLs with CGI-scripts, to force them to be
  1290.       processed by the CGI-script, it's likely that you 
  1291.           will run into problems (or significant overhead) on
  1292.           sub-requests. In these cases, use this flag.
  1293.         </li>
  1294.  
  1295.         <li>
  1296.           '<strong><code>proxy|P</code></strong>' (force
  1297.           <strong>p</strong>roxy)<br />
  1298.           This flag forces the substitution part to be internally
  1299.       sent as a proxy request and immediately (rewrite 
  1300.       processing stops here) put through the <a href="mod_proxy.html">proxy module</a>. You must make
  1301.           sure that the substitution string is a valid URI
  1302.           (typically starting with
  1303.           <code>http://</code><em>hostname</em>) which can be
  1304.           handled by the Apache proxy module. If not, you will get an
  1305.           error from the proxy module. Use this flag to achieve a
  1306.           more powerful implementation of the <a href="mod_proxy.html#proxypass">ProxyPass</a> directive,
  1307.           to map remote content into the namespace of the local
  1308.           server. 
  1309.  
  1310.           <p>Note: <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> must be enabled in order
  1311.           to use this flag.</p>
  1312.         </li>
  1313.  
  1314.         <li>
  1315.           '<strong><code>passthrough|PT</code></strong>'
  1316.           (<strong>p</strong>ass <strong>t</strong>hrough to next
  1317.           handler)<br />
  1318.            This flag forces the rewrite engine to set the
  1319.           <code>uri</code> field of the internal
  1320.           <code>request_rec</code> structure to the value of the
  1321.           <code>filename</code> field. This flag is just a hack to
  1322.           enable post-processing of the output of
  1323.           <code>RewriteRule</code> directives, using
  1324.           <code>Alias</code>, <code>ScriptAlias</code>,
  1325.           <code>Redirect</code>, and other directives from
  1326.           various URI-to-filename translators. For example, to rewrite
  1327.           <code>/abc</code> to <code>/def</code> using
  1328.           <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>, and then
  1329.           <code>/def</code> to <code>/ghi</code> using
  1330.           <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code>: 
  1331. <div class="example"><p><code>
  1332.     RewriteRule ^/abc(.*)  /def$1 [PT]<br />
  1333.     Alias       /def       /ghi
  1334. </code></p></div>
  1335.           If you omit the <code>PT</code> flag,
  1336.           <code>mod_rewrite</code> will rewrite 
  1337.       <code>uri=/abc/...</code> to
  1338.           <code>filename=/def/...</code> as a full API-compliant
  1339.           URI-to-filename translator should do. Then
  1340.           <code>mod_alias</code> will try to do a
  1341.           URI-to-filename transition, which will fail. 
  1342.  
  1343.           <p>Note: <strong>You must use this flag if you want to
  1344.           mix directives from different modules which allow
  1345.           URL-to-filename translators</strong>. The typical example
  1346.           is the use of <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> and
  1347.           <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>.</p>
  1348.         </li>
  1349.  
  1350.         <li>'<strong><code>qsappend|QSA</code></strong>'
  1351.         (<strong>q</strong>uery <strong>s</strong>tring
  1352.         <strong>a</strong>ppend)<br />
  1353.         This flag forces the rewrite engine to append a query
  1354.         string part of the substitution string to the existing string,
  1355.         instead of replacing it. Use this when you want to add more
  1356.         data to the query string via a rewrite rule.</li>
  1357.  
  1358.          <li>'<strong><code>redirect|R</code>
  1359.           [=<em>code</em>]</strong>' (force <a id="redirect" name="redirect"><strong>r</strong>edirect</a>)<br />
  1360.           Prefix <em>Substitution</em> with
  1361.           <code>http://thishost[:thisport]/</code> (which makes the
  1362.           new URL a URI) to force a external redirection. If no
  1363.           <em>code</em> is given, a HTTP response of 302 (MOVED
  1364.           TEMPORARILY) will be returned. If you want to use other response
  1365.           codes in the range 300-400, simply specify the appropriate number
  1366.           or use one of the following symbolic names:
  1367.           <code>temp</code> (default), <code>permanent</code>,
  1368.           <code>seeother</code>. Use this for rules to
  1369.           canonicalize the URL and return it to the client - to 
  1370.       translate ``<code>/~</code>'' into
  1371.           ``<code>/u/</code>'', or to always append a slash to
  1372.           <code>/u/</code><em>user</em>, etc.<br />
  1373.           <strong>Note:</strong> When you use this flag, make
  1374.           sure that the substitution field is a valid URL! Otherwise,
  1375.           you will be redirecting to an invalid location. Remember
  1376.           that this flag on its own will only prepend
  1377.           <code>http://thishost[:thisport]/</code> to the URL, and rewriting
  1378.       will continue. Usually, you will want to stop rewriting at this point,
  1379.       and redirect immediately. To stop rewriting, you should add 
  1380.       the 'L' flag.
  1381.         </li>
  1382.  
  1383.         <li>'<strong><code>skip|S</code></strong>=<em>num</em>'
  1384.         (<strong>s</strong>kip next rule(s))<br />
  1385.         This flag forces the rewriting engine to skip the next
  1386.         <em>num</em> rules in sequence, if the current rule
  1387.         matches. Use this to make pseudo if-then-else constructs:
  1388.         The last rule of the then-clause becomes
  1389.         <code>skip=N</code>, where N is the number of rules in the
  1390.         else-clause. (This is <strong>not</strong> the same as the
  1391.         'chain|C' flag!)</li>
  1392.  
  1393.         <li>
  1394.         '<strong><code>type|T</code></strong>=<em>MIME-type</em>'
  1395.         (force MIME <strong>t</strong>ype)<br />
  1396.          Force the <a class="glossarylink" href="../glossary.html#mime-type" title="see glossary">MIME-type</a> of the target file to be
  1397.         <em>MIME-type</em>. This can be used to
  1398.         set up the content-type based on some conditions.
  1399.         For example, the following snippet allows <code>.php</code> files to
  1400.         be <em>displayed</em> by <code>mod_php</code> if they are called with
  1401.         the <code>.phps</code> extension:
  1402.         <div class="example"><p><code>
  1403.             RewriteRule ^(.+\.php)s$ $1 [T=application/x-httpd-php-source]
  1404.         </code></p></div>
  1405.         </li>
  1406.       </ul>
  1407.  
  1408. <div class="note"><h3>Note: Enabling rewrites in per-directory context</h3>
  1409.  To enable the rewrite engine
  1410.           for per-directory configuration files you need to set
  1411.           ``<code>RewriteEngine On</code>'' in these files
  1412.           <strong>and</strong> ``<code>Options
  1413.           FollowSymLinks</code>'' must be enabled. If your
  1414.           administrator has disabled override of
  1415.           <code>FollowSymLinks</code> for a user's directory, then
  1416.           you cannot use the rewrite engine. This restriction is
  1417.           required for security reasons.
  1418. </div>
  1419.  
  1420. <div class="note"><h3>Note: Pattern matching in per-directory context</h3> 
  1421.     Never forget that <em>Pattern</em> is
  1422. applied to a complete URL in per-server configuration
  1423. files. <strong>However, in per-directory configuration files, the
  1424. per-directory prefix (which always is the same for a specific
  1425. directory) is automatically <em>removed</em> for the pattern matching
  1426. and automatically <em>added</em> after the substitution has been
  1427. done.</strong> This feature is essential for many sorts of rewriting - 
  1428. without this, you would always have to match the parent
  1429. directory, which is not always possible.
  1430.  
  1431.             <p>There is one exception: If a substitution string
  1432.             starts with ``<code>http://</code>'', then the directory
  1433.             prefix will <strong>not</strong> be added ,and an
  1434.             external redirect (or proxy throughput, if using flag
  1435.             <strong>P</strong>) is forced!</p>
  1436. </div>
  1437.  
  1438. <div class="note"><h3>Note: Substitution of Absolute URLs</h3>
  1439.           <p>
  1440.           When you prefix a substitution field with
  1441.       <code>http://thishost[:thisport]</code>, <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> will automatically strip that
  1442.           out. This auto-reduction on URLs with an implicit 
  1443.           external redirect is most useful in
  1444.           combination with a mapping-function which generates the
  1445.       hostname part.</p>
  1446.  
  1447.           <p><strong>Remember:</strong> An unconditional external
  1448.           redirect to your own server will not work with the prefix
  1449.           <code>http://thishost</code> because of this feature. To
  1450.           achieve such a self-redirect, you have to use the
  1451.           <strong>R</strong>-flag.</p>
  1452. </div>
  1453.  
  1454. <div class="note"><h3>Note: Query String</h3>
  1455.       <p>The <em>Pattern</em> will not be matched against the query string.
  1456.       To do this, you must use a <code class="directive"><a href="#rewritecond">RewriteCond</a></code> with the
  1457.       <code>%{QUERY_STRING}</code> variable. You can, however, create
  1458.       URLs in the substitution string, containing a query string
  1459.       part. Simply use a question mark inside the substitution string, to
  1460.       indicate that the following text should be re-injected into the
  1461.       query string. When you want to erase an existing query string,
  1462.       end the substitution string with just a question mark. To
  1463.       combine new and old query strings, use the
  1464.       <code>[QSA]</code> flag.</p>
  1465. </div>
  1466.  
  1467.      <p>Here are all possible substitution combinations and their
  1468.       meanings:</p>
  1469.  
  1470.       <p><strong>Inside per-server configuration
  1471.       (<code>httpd.conf</code>)<br />
  1472.        for request ``<code>GET
  1473.       /somepath/pathinfo</code>'':</strong><br />
  1474.       </p>
  1475.  
  1476. <div class="note"><pre>
  1477. <strong>Given Rule</strong>                                      <strong>Resulting Substitution</strong>
  1478. ----------------------------------------------  ----------------------------------
  1479. ^/somepath(.*) otherpath$1                      invalid, not supported
  1480.  
  1481. ^/somepath(.*) otherpath$1  [R]                 invalid, not supported
  1482.  
  1483. ^/somepath(.*) otherpath$1  [P]                 invalid, not supported
  1484. ----------------------------------------------  ----------------------------------
  1485. ^/somepath(.*) /otherpath$1                     /otherpath/pathinfo
  1486.  
  1487. ^/somepath(.*) /otherpath$1 [R]                 http://thishost/otherpath/pathinfo
  1488.                                                 via external redirection
  1489.  
  1490. ^/somepath(.*) /otherpath$1 [P]                 doesn't make sense, not supported
  1491. ----------------------------------------------  ----------------------------------
  1492. ^/somepath(.*) http://thishost/otherpath$1      /otherpath/pathinfo
  1493.  
  1494. ^/somepath(.*) http://thishost/otherpath$1 [R]  http://thishost/otherpath/pathinfo
  1495.                                                 via external redirection
  1496.  
  1497. ^/somepath(.*) http://thishost/otherpath$1 [P]  doesn't make sense, not supported
  1498. ----------------------------------------------  ----------------------------------
  1499. ^/somepath(.*) http://otherhost/otherpath$1     http://otherhost/otherpath/pathinfo
  1500.                                                 via external redirection
  1501.  
  1502. ^/somepath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
  1503.                                                 via external redirection
  1504.                                                 (the [R] flag is redundant)
  1505.  
  1506. ^/somepath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
  1507.                                                 via internal proxy
  1508. </pre></div>
  1509.  
  1510.       <p><strong>Inside per-directory configuration for
  1511.       <code>/somepath</code><br />
  1512.        (<code>/physical/path/to/somepath/.htacccess</code>, with
  1513.       <code>RewriteBase /somepath</code>)<br />
  1514.        for request ``<code>GET
  1515.       /somepath/localpath/pathinfo</code>'':</strong><br /> 
  1516.      </p>
  1517.  
  1518. <div class="note"><pre>
  1519. <strong>Given Rule</strong>                                      <strong>Resulting Substitution</strong>
  1520. ----------------------------------------------  ----------------------------------
  1521. ^localpath(.*) otherpath$1                      /somepath/otherpath/pathinfo
  1522.  
  1523. ^localpath(.*) otherpath$1  [R]                 http://thishost/somepath/otherpath/pathinfo
  1524.                                                 via external redirection
  1525.  
  1526. ^localpath(.*) otherpath$1  [P]                 doesn't make sense, not supported
  1527. ----------------------------------------------  ----------------------------------
  1528. ^localpath(.*) /otherpath$1                     /otherpath/pathinfo
  1529.  
  1530. ^localpath(.*) /otherpath$1 [R]                 http://thishost/otherpath/pathinfo
  1531.                                                 via external redirection
  1532.  
  1533. ^localpath(.*) /otherpath$1 [P]                 doesn't make sense, not supported
  1534. ----------------------------------------------  ----------------------------------
  1535. ^localpath(.*) http://thishost/otherpath$1      /otherpath/pathinfo
  1536.  
  1537. ^localpath(.*) http://thishost/otherpath$1 [R]  http://thishost/otherpath/pathinfo
  1538.                                                 via external redirection
  1539.  
  1540. ^localpath(.*) http://thishost/otherpath$1 [P]  doesn't make sense, not supported
  1541. ----------------------------------------------  ----------------------------------
  1542. ^localpath(.*) http://otherhost/otherpath$1     http://otherhost/otherpath/pathinfo
  1543.                                                 via external redirection
  1544.  
  1545. ^localpath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
  1546.                                                 via external redirection
  1547.                                                 (the [R] flag is redundant)
  1548.  
  1549. ^localpath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
  1550.                                                 via internal proxy
  1551. </pre></div>
  1552.   
  1553. </div>
  1554. </div>
  1555. <div class="bottomlang">
  1556. <p><span>Available Languages: </span><a href="../en/mod/mod_rewrite.html" title="English"> en </a></p>
  1557. </div><div id="footer">
  1558. <p class="apache">Copyright 1995-2006 The Apache Software Foundation or its licensors, as applicable.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
  1559. <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
  1560. </body></html>